home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / arexx_cl.doc < prev    next >
Encoding:
Text File  |  1999-10-29  |  8.6 KB  |  225 lines
  1. TABLE OF CONTENTS
  2.  
  3. arexx_cl/--datasheet--
  4. arexx_cl/AM_EXECUTE
  5. arexx_cl/AM_HANDLEINPUT
  6. arexx_cl/--datasheet--                                 arexx_cl/--datasheet--
  7.  
  8.     NAME
  9.         arexx_cl -- ARexx interface class.
  10.  
  11.     SUPERCLASS
  12.         rootclass
  13.  
  14.     DESCRIPTION
  15.         This class provides you with a very easy way to implement an ARexx
  16.         interface.  It will setup a unique ARexx port, start ARexx macros,
  17.         parse commands and dispatch command handler functions.
  18.  
  19.         All ARexx class methods and the callbacks you provide it are run in
  20.         the context of the task you call ARexx class from. Thus if your
  21.         application is a process, DOS is safe to use.
  22.  
  23.     METHODS
  24.         OM_NEW -- Passed to superclass first.  Sets up the port.
  25.  
  26.         OM_GET -- Returns requested attributes.  Passed onto superclass.
  27.  
  28.         OM_DISPOSE -- Closes the port and frees all resources.  Passed onto
  29.             superclass
  30.  
  31.         AM_EXECUTE -- Executes an ARexx command or macro.
  32.  
  33.         AM_HANDLEINPUT -- Handles ARexx messages.
  34.  
  35.     ATTRIBUTES
  36.         AREXX_HostName (STRPTR)
  37.             The name of the host.  The ARexx portname is derived from this.
  38.             In pretty much all cases, this should the same as your app's
  39.             basename.  You should refrain from using names like "MYPROG_RX"
  40.             or others with unnecessary suffixes.
  41.  
  42.             To create the portname, the hostname will be uppercased, and,
  43.             unless AREXX_NoSlot is specified, a slot number will be
  44.             appended.
  45.  
  46.             Applicability is (OM_NEW, OM_GET)
  47.  
  48.         AREXX_NoSlot (BOOL)
  49.             Specifies that no slot number should be appended to the port
  50.             name when it is being created.  This greatly increases the
  51.             chances that your requested portname is in use, so your code
  52.             must be sure to handle this situation.
  53.  
  54.             Defaults to FALSE.
  55.  
  56.             Applicability is (OM_NEW)
  57.  
  58.         AREXX_DefExtension (STRPTR)
  59.             Default filename extension for macros started by your app.  Do
  60.             not include the ".", just the extension text.   In pretty much
  61.             all cases, this should be the same as your app's basename.  You
  62.             should refrain from using extensions like "myrx".
  63.  
  64.             Defaults to "rexx".
  65.  
  66.             Applicability is (OM_NEW)
  67.  
  68.         AREXX_Commands (struct ARexxCmd *)
  69.             The table of the commands supported by your ARexx interface.
  70.             This will be a pointer to an array of struct ARexxCmd.  If this
  71.             array is not passed then your host will not be able to process
  72.             any ARexx commands.
  73.  
  74.             The following fields must be setup initially by the app before
  75.             OM_NEW:
  76.  
  77.                 ac_Name (STRPTR)
  78.                 The name of the command.  By convention this is usually all
  79.                 uppercase, though a case-insensitive comparisons will be
  80.                 done.
  81.  
  82.                 ac_ID (WORD)
  83.                 A unique number identifying this command.
  84.  
  85.                 ac_Func (*()(struct ARexxCmd *, struct RexxMsg *))
  86.                 A pointer to the function that will be called when this
  87.                 command is received by your programme.  The function will
  88.                 get past a pointer to its ARexxCmd entry and the RexxMsg
  89.                 structure received for the command.  You may use this
  90.                 for setting ARexx variables, but please note that is may
  91.                 be NULL
  92.  
  93.                 ac_ArgTemplate (STRPTR)
  94.                 DOS ReadArgs()-style argument template for this command.
  95.  
  96.                 ac_Flags (ULONG)
  97.                 Command flags.  Currently unused, but in order to remain
  98.                 compatable, you must ensure that this is NULL.
  99.  
  100.             These fields are ignored in OM_NEW and are set by the class
  101.             when calling the ac_Func command callback.
  102.  
  103.                 ac_ArgList (ULONG *)
  104.                 Result of ReadArgs() using the arguments received with the
  105.                 command and ac_ArgTemplate as the template.
  106.  
  107.                 ac_RC (LONG)
  108.                 Primary result, the RC variable.  Also causes the RC2
  109.                 variable to return, and will cause RESULT to NOT be set.
  110.  
  111.                 ac_RC2 (LONG)
  112.                 Secundary result, the RC2 variable.  This will not be set
  113.                 unless RC is non-zero.
  114.  
  115.                 ac_Result (STRPTR)
  116.                 RESULT variable, this should be a string.  If you want to
  117.                 return a number, you will have to convert it to a string
  118.                 first.  This string will not be set if RC is non-zero.
  119.  
  120.             The array must be terminated with a NULL ac_Name field.
  121.  
  122.             Applicability is (OM_NEW)
  123.  
  124.         AREXX_ErrorCode (ULONG *)
  125.             A pointer to storage space for OM_NEW to store an error code
  126.             when it fails trying to create the object.  Possible values
  127.             are:
  128.  
  129.             RXERR_NO_COMMAND_LIST - No command list was provided.
  130.             RXERR_NO_PORT_NAME - No host base name was provided.
  131.             RXERR_PORT_ALREADY_EXISTS - The  class  was unable to create a
  132.                 unique name of the base name you provided.
  133.             RXERR_OUT_OF_MEMORY - Not enough free memory.
  134.  
  135.             No error code will be returned if you provide a NULL pointer.
  136.  
  137.             Defaults NULL.
  138.  
  139.             Applicability is (OM_NEW)
  140.  
  141.         AREXX_SigMask (ULONG)
  142.             The signal mask for the object's message port.  This is the
  143.             signal you will want to Wait() on so you know when there is
  144.             activity at the ARexx port.
  145.  
  146.             Applicability is (OM_GET)
  147.  
  148.         AREXX_ReplyHook (struct Hook *)
  149.             This is a function hook that will get called whenever your host
  150.             replies to an ARexx message.  This generally happens after your
  151.             host has sent a message (eg. via AM_EXECUTE) and the task
  152.             receiving the message has completed its processing with the
  153.             message.  This is most useful for checking return codes from
  154.             commands sent via AM_EXECUTE.
  155.  
  156.             The object parameter in the hook function will point to the
  157.             Object * that is yur host, and the message parameter will be
  158.             the ARexx message that is being replied to (from which you
  159.             could extract result codes).
  160.  
  161.             Defaults to NULL.
  162.  
  163.             Applicability is (OM_NEW, OM_GET)
  164.  
  165.     BUGS
  166.         AREXX_HostName MUST be all uppercase in V40 otherwise the checks for
  167.         an already existing port won't work right.
  168. arexx_cl/AM_EXECUTE                                       arexx_cl/AM_EXECUTE
  169.  
  170.     NAME
  171.         AM_EXECUTE -- Execute an ARexx macro.
  172.  
  173.     FUNCTION
  174.         This method allows you to execute a macro in another host.  The
  175.         default host is the ARexx server.  This is how you would execute
  176.         disk-based ARexx macros, by passing the name of the file as the
  177.         command string to the ARexx server.
  178.  
  179.         This method uses the following custom message structure:
  180.  
  181.           struct apExecute
  182.           {
  183.               ULONG MethodID;
  184.               STRPTR ape_CommandString;
  185.               STRPTR ape_PortName;
  186.               LONG *ape_RC;
  187.               LONG *ape_RC2;
  188.               STRPTR *ape_Result;
  189.               BPTR ape_IO;
  190.           };
  191.  
  192.         ape_CommandString (STRPTR)
  193.             This must point to the command including arguments to execute.
  194.             If the command is found in the host command list it will be
  195.             executed.  Unknown commands will be shipped off to the ARexx
  196.             server.
  197.  
  198.         ape_RC, ape_RC2, ape_Result (LONG *, LONG *, STRPTR *)
  199.             After the command executed you will find the results in here if
  200.             the command was one in your host, or if there was a problem
  201.             sending the command to the specified host.  You will NOT get the
  202.             result of the command if it is sent to another host, since the
  203.             command is sent asychronously.  Use AREXX_ReplyHook for this.
  204.  
  205.         ape_IO (BPTR)
  206.             If you execute a script using this method you can pass a pointer
  207.             to the IO channel ARexx must  use here.  This IO channel will be
  208.             closed automatically for you after the command executed.
  209.  
  210.     RESULT
  211.         As errors are reported in acme_RC and acme_RC2 this method has no
  212.         specific return code.
  213. arexx_cl/AM_HANDLEINPUT                               arexx_cl/AM_HANDLEINPUT
  214.  
  215.     NAME
  216.         AM_HANDLEINPUT
  217.  
  218.     FUNCTION
  219.         This method will handle all incoming and outgoing message traffic
  220.         from your host.  When you are signalled you simply call this method
  221.         and everything is done for you.
  222.  
  223.     RESULT
  224.         No return code is specified for this method.
  225.